接下來就從兩大主題豐收款消費支付API與Shioaji證券API之間，挑一個來進行，既然證券開盤時間在上班有點難研究Shioaji，不要把事情搞的太複雜，就順著感覺走，就先來研究豐收款消費支付API這個題目。

API開發規格書寫的方式是把這整套API能做的功能依應用場景來說明，以羅列與解釋達成目標的作法為目的，這固然對於想要著手開發的人而言是正確的，不過如果我們就只是純粹照著作，然後在這裡把規格書的東西複誦一遍，好像也沒什麼意思，那就直接看文件就好了，畢竟寫的還算蠻詳細的。

所以撰寫技術blog的用意與真諦，就是設法身處和你一樣情境與的人的位置，用更貼近新手視角的方式來詮釋「同一件事」，除了自己懂，也設法讓別人也會同理解。因此除了一起試著動手作之外，也會多出一些廢話來解釋我的看法與理解。同步好這些觀點後，就可以開始了！

我從永豐那收到的東西

首先，報名鐵人賽以及填妥要和永豐金索取的資料後，會收到Email，取得一些資料，接下來就是解釋一下這些資料是幹麻的，以及為什麼會需要這些資料。

Email內容如下

感謝參加2021年之iThome鐵人賽，永豐銀行以「消費支付API」為參考題目，提供給參賽者的試用資料請點連結下載，檔案包括：

API串接手冊
Sample code
測試金鑰

另提供您開發重要串接資料如下：
(1) 商店代號 (Shop No )：NA0249_001 。
(2) Hash值 (四組)：產出運算值 (Hash ID) 以計算出安全簽章及訊息加密用 。
A1 : 86D50DEF3EB7400E
A2 : 01FD27C09E5549E5
B1 : 9E004965F4244953
B2 : 7FB3385F414E4F91

1. 商店資訊，Who am I?

如果不是參加鐵人賽，那誰會去和永豐申請消費支付API？ 難不成是消費者因為想要用線上支付所以自己去申請API來串接嗎 (應該沒有這種苦命事)？

因此，當然是賣方角色。

如果你只是一個獨立小店家(例如僅有小量產品，或經銷、批貨商等)，且不具備網站架設與系統開發能力，多半會選擇加入各大電子商城或拍賣平台等，由該平台提供的既有支付服務來達成提供顧客消費支付服務的目標。因此，我們的情境角色，多半不會是這一類型的賣家。但如果真的有小型獨立店家想這麼做可以嗎，當然可以。

因此，以較合理方式來看，這個賣方的角色會是具備網站系統開發能力，想發展一個電商平台的業者，但希望自己聚焦在購物系統的設計本身，而將金流處理的部份直接和既有的銀行服務作串接(就是透過API)，以提供給顧客有多元的消費支付服務，這樣的設想會較為合理。

所以如果是這樣的角色，我們才會需要和豐永銀行申請消費支付API的串接。但實際的情境，正式申請時想必會需要提交更多的相關資料給銀行端，經審查之後才會收到實際的商家端資料。

我們繼續盤點一下我們的重要資料：

• 商店代號： NA0249_001
• Hash值(四組)：A1、A2、B1、B2

商店代號，代表我們是誰，要和銀行後續進行各種API串接服務，總要讓銀行知道你是哪一個商家要跟他作後續資料交換。
而Hash值呢，畢竟這是高度資安等級的金流交易，因此為了要確保資料交換過程均是有在高度驗證性與識別度的運作原則下進行，可以想成是銀行特別為你所準備的安全識別碼。(還會做一些加工手法)

2. 豐收款API能提供我做什麼

在釐清上述角色與假想後，如果我是一個電商平台，那銀行提供的外部金流的服務會發生在我的電商服務流程的哪個階段？

• 顧客在購物車商品確認後，訂單成立，要讓顧客進行所選定的付款流程：
  • 提供付款功能 --> 對應到「建立訂單交易」
• 若顧客立即付完款後，原本停留的頁面可轉入下個流程：
  • 提供付款後轉回店商頁面 --> 對應到「建立訂單交易」
• 訂單成立和付款是分開來看的流程，使用者不一定要在訂單成立就立即付款：
  • 能夠依條件供店家查詢訂單付款狀態 --> 對應到「訂單交易查詢」
• 依明確的付款代碼(Token)進行付款狀態之查詢(有執行付款動作不一定代表成功)：
  • 依付款代碼查詢狀態 --> 對應到「訊息查詢服務」
• 若顧客在之後付款完成後，銀行端可通知店家 (由店家提供URL)：
  • 付款完成回呼服務 --> 對應到「建立訂單交易」
• 若收到付款完成回呼後，再主動與銀行端作確認回報：
  • 店家向銀行作回呼服務接收確認 --> 對應到「即時訊息通知」

3. 串接連線的準備工作

前面先說明的是交握的情境與流程，接著就是回到程式技術本身了。

以下是豐收款API的幾項規定：

1. 在API的連線過程，會需要以TLS 1.2來建立HTTPS的安全機制。
   註：舊版的TLS 1.0、1.1以及SSL 2.0、3.0均因為資安風險，有潛在的弱點會藉此進行網路攻擊等行為，業界幾乎都設定為關閉停用。
2. 使用UTF-8編碼
3. 使用JSON格式

• 其中我們能使用的僅為測試環境，其API網址如下：
  https://apisbx.sinopac.com/funBIZ/QPay.WebAPI/api/Order

• 而測試環境提供的Nonce取用網址
  https://apisbx.sinopac.com/funBIZ/QPay.WebAPI/api/

什麼是Nonce?

Nonce是一個短時間即失效(60秒)的Token (由API方所提供)，其設計是為了作為API呼叫方的安全驗證的一個運算要素，傳送後會由API接收方進行比對。而短時間即過期的目的，是為了提高資料不幸被攔截後破解與分析的難度，讓「破解」成本過高到破解者不會想要嘗試，簡單來說是為了防止資訊被拆解後的重送攻擊。
基本上，在每次叫用API時的第一個必要的步驟，就是重新取得一次Nonce。

先拿回一個Nonce來看一看吧

打開Postman，將上述Nonce取用網址輸入，文件上沒特別說明Method的使用，但須使用POST方式進行呼叫。

在使用這個API時，必須於request傳入必要內容：告訴API你是哪個店家！
還記得我們的商店代號叫「NA0249_001」吧。

傳入格式如上述說明，均使用JSON，所以在Postman中，網址填好後，在Body區選擇raw與JSON類型，即可將準備好的request一併傳給API。

{
    "ShopNo":"NA0249_001"
}

於是乎，就可以看到熱騰騰的Nonce從API回傳回來了！

先做到這兒，確認可以運作之後，接下來再來用Python程式叫用吧。